home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / os2 / gg243774.zip / README.TXT < prev    next >
Text File  |  1992-06-02  |  16KB  |  366 lines
  1. ***********************************************************************
  2. ***                                                                 ***
  3. *** IBM International Technical Support Center, Boca Raton, Florida ***
  4. ***                                                                 ***
  5. ***              OS/2 Version 2.0 Technical Compendium              ***
  6. ***                                                                 ***
  7. ***                           GBOF-2254                             ***
  8. ***                                                                 ***
  9. ***                        Sample Code for                          ***
  10. ***                                                                 ***
  11. ***       OS/2 Version 2.0 - Volume 4: Application Development      ***
  12. ***                                                                 ***
  13. ***                           GG24-3774                             ***
  14. ***                                                                 ***
  15. ***********************************************************************
  16.  
  17.  
  18. Please use the PKZIP shareware utility to unpack the files.
  19.  
  20. *************************** Disclaimer ********************************
  21.  
  22. References in this package to IBM products, programs or services do not
  23. imply that IBM intends to make these available in all countries in which
  24. IBM operates.  Any reference to an IBM product, program, or service is not
  25. intended to state or imply that only IBM's product, program, or service may
  26. be used.  Any functionally equivalent program that does not infringe any of
  27. IBM's intellectual property rights may be used instead of the IBM product,
  28. program or service.
  29.  
  30. Information in this package was developed in conjunction with use of the
  31. equipment specified, and is limited in application to those specific
  32. hardware and software products and levels.
  33.  
  34. IBM may have patents or pending patent applications covering subject matter
  35. in this package.  The furnishing of this package does not give you any
  36. license to these patents.  You can send license inquiries, in writing, to
  37. the IBM Director of Commercial Relations, IBM Corporation, Purchase,
  38. NY 10577.
  39.  
  40. The information contained in this package has not been submitted to any
  41. formal IBM test and is distributed AS IS.
  42.  
  43. The use of this information or the implementation of any of these
  44. techniques is a customer responsibility and depends on the customer's
  45. ability to evaluate and integrate them into the customer's operational
  46. environment.  While each item may have been reviewed by IBM for accuracy in
  47. a specific situation, there is no guarantee that the same or similar
  48. results will be obtained elsewhere.  Customers attempting to adapt these
  49. techniques to their own environments do so at their own risk.
  50.  
  51. This package contains examples of data used in daily
  52. business operations.  To illustrate them as completely as possible, the
  53. examples contain the names of individuals, companies, brands, and products.
  54. All of these names are fictitious and any similarity to the names and
  55. addresses used by an actual business enterprise is entirely coincidental.
  56.  
  57. *********************** End of Disclaimer *****************************
  58.  
  59.  
  60. Notes on WPS Redbook Examples
  61. =============================
  62.  
  63. General
  64.  
  65. The WPS samples each come with the following REXX programs:
  66.  
  67.  - ADD.CMD
  68.    This installs the example classes and should only be done once
  69.    for each example, (Re-boot is required to perform the
  70.    ADD.CMD for a second example).
  71.  
  72.  - TEST.CMD
  73.    This creates the objects
  74.  
  75.  - REMOVE.CMD
  76.    This Deregisters the classes. Re-boot is required after
  77.    this step, then the DLLs that ADD.CMD copied in to the
  78.    \OS2\DLL directory may be deleted.
  79.  
  80.  - BUILD.CMD
  81.    This runs the NMAKE utility for the samples.
  82.    The way the make files are set up they expect the
  83.    toolkit to be installed on the C drive, and the
  84.    CSET environment to be set.
  85.  
  86. 1.PWFolder class example
  87.  
  88. Files:  PWFOLDER.DLL  - A WPFolder derived class that can be locked
  89.                         with a user specified password
  90.  
  91. The PWFolder password is passed in via a Setup string. For the
  92. example TEST.CMD sets the password to "wps" by specifying
  93. "PASSWORD=wps;" setup string in the SysCreateObject command.
  94.  
  95.  
  96. 2.Record Class example
  97.  
  98. Files:  RECORD.DLL    - Transient record class
  99.         RECFLDER.DLL  - WPFolder derived class that has
  100.                         a context menu option to do a telephone
  101.                         list find.
  102.         SERVER.EXE    - Sever program (pretends to access a database
  103.                         but actually reads the names and address from
  104.                         an ASCII file; c:\names.dat).
  105.  
  106.  
  107.  
  108. The Record class has been broken down in to separate threads
  109. and processes as follows:
  110.  
  111.      WPS        │      WPS Process   ││   Second Process
  112.      Thread            New Thread
  113.                 │                    ││
  114.  
  115.                 │      Client        ││     Server
  116.    ┌─────────┐       ┌───────────┐        ┌───────────┐
  117.    │ Record  │  │    │ Database  │   ││   │ Database  │
  118.    │ Class   │       │ requester │        │ server    │
  119.    │         │  │    │ PM object │   ││   │ PM object │
  120.    └─────────┘       │ window    │        │ window    │
  121.                 │    └───────────┘   ││   └───────────┘
  122.  
  123.                 │                    ││   ┌────────┐
  124.                                           │ ┌────────┐    Perform
  125.                 │                    ││   │ │ ┌────────┐  actual
  126.                                           └─│ │ Work   │  searches
  127.                 │                    ││     └─│ Thread │
  128.                                               └────────┘
  129.  
  130.  
  131. The Record class receives messages to search its database
  132. and instantiate new records from a folder object.
  133.  
  134.                   Folder object                Record Class
  135.                  ┌───────────────────┐        ┌───────────────────┐
  136.                  │                   │        │                   │
  137.   ┌────┐         ├───────────────────┤        ├───────────────────┤
  138.   │User│ ───────>│Search for records │───────>│clsQueryDatabase   │
  139.   └────┘         ├───────────────────┤        ├───────────────────┤
  140.                  │                   │        │                   │
  141.                  └───────────────────┘        └───────────────────┘
  142. To enable the object communication between the Folder object and
  143. the Record class we do the following:
  144.  
  145. In the folder class .C
  146.  
  147.         #include "record.h"
  148.  
  149. In the folder class .DEF
  150.  
  151.         IMPORTS
  152.            record.RecordCClassData
  153.            record.RecordClassData
  154.            record.RecordNewClass
  155.            record.M_RecordCClassData
  156.            record.M_RecordClassData
  157.            record.M_RecordNewClass
  158.  
  159. This allows us to directly call the Record class method:
  160.  
  161.       _clsQueryDatabase(RecordClass, pQuery, Folder);
  162.  
  163.  
  164.  
  165.  
  166. The record class processes the _clsQueryDatabase method by
  167. copying all the necessary information to a newly allocated
  168. block of shared memory and sending it to the Requester PM
  169. object window.
  170.  
  171.    Record Class object
  172.    ┌─────────────────────┐     ┌────────┐
  173.    │ _clsQueryDatabase() │     │Shared  │     Requester Object window
  174.    │                     │     │memory  │     ┌───────────────────┐
  175.    │  DosAllocShrMem     │     └────────┘     │        .          │
  176.    │  <Fill memory>      │     WinSendMsg     │        .          │
  177.    │  WinSendMsg         │ ──────────────────>│ case WMP_DO_FIND: │
  178.    │                     │                    │        .          │
  179.    └─────────────────────┘                    │        .          │
  180.                                               └───────────────────┘
  181.  
  182. The Requester object window passes the message on
  183. to the Server object window and then frees it from its
  184. own process. A successful transfer has been made the
  185. memory is now "owned" soley by the Server process.
  186.  
  187.   Requester Object window
  188.   ┌───────────────────┐       ┌────────┐
  189.   │         .         │       │Shared  │     Server Object window
  190.   │         .         │       │memory  │     ┌───────────────────┐
  191.   │ case WMP_DO_FIND: │       └────────┘     │        .          │
  192.   │  DosGiveShrMem    │     WinSendMsg       │        .          │
  193.   │  WinSendMsg       │─────────────────────>│ case WMP_DO_FIND: │
  194.   │  DosFreeMem       │                      │        .          │
  195.   └───────────────────┘                      │        .          │
  196.                                              └───────────────────┘
  197.  
  198. The server now looks at the content message, specifically
  199. if the query is null it means that the folder object did
  200. send any query data, and a dialog should be created to ask the
  201. user for some query data. It is worth noting that to bring up
  202. the dialog box the server object window sends a message to
  203. the main server application window; this is due to the fact
  204. that UI windows cannot be created in HWND_OBJECT threads.
  205.  
  206. Once a valid query is ready a work thread is started to
  207. search the database. The results found are sent back to
  208. server object window and the thread terminates.
  209.  
  210.  
  211.       ┌──────────┐  Start Thread    ┌────────┐
  212.       │ Database │─ ─ ─ ─ ─ ─ ─ ─ ─>│ Work   │ Perform search
  213.       │ server   │    DO_FIND       │ Thread │ DosAllocShrMem [results]
  214.       │ object   │                  └────────┘ DosFreeMem [query data]
  215.       │ window   │<───────┐              │
  216.       └──────────┘        │              │
  217.                           └──────────────┘
  218.                              RESULTS
  219.  
  220.  
  221.  
  222.  
  223.  
  224. On receiving the results the server object window in turn
  225. passes them back to the Requester object window. Using the
  226. results data the Requester object window creates new
  227. record objects inside the folder that requested the
  228. search in the first place.
  229.  
  230.       ┌──────────┐
  231.       │ Database │ DosGiveShrMem [results]
  232.       │ server   │
  233.       │ object   │ DosFreeMem [results]
  234.       │ window   │ (after sending)
  235.       └──────────┘
  236.            │
  237.            │                          ┌─┬──────────────────────────┬─┬─┐
  238.            │                          ├─┴──────────────────────────┴─┴─┤
  239.            │RESULTS                   │                                │
  240.            │                          │          ┌────┐                │
  241.            V                          │          │    │     ┌────┐     │
  242.       ┌───────────┐                   │          └────┘     │    │     │
  243.       │ Database  │    _wpclsNew      │      ┌────┐         └────┘     │
  244.       │ requester │  ───────────────────────>│    │                    │
  245.       │ object    │                   │      └────┘                    │
  246.       │ window    │                   │                                │
  247.       └───────────┘                   └────────────────────────────────┘
  248.        DosFreeMem [results]
  249.  
  250.  
  251. Notes on DROPINFO Example
  252. =========================
  253.  
  254. The DROPINFO example displays the contents of the DRAGINFO and DRAGITEM data
  255. structures whenever another object is dropped over the DROPINFO program's
  256. window.  This example is intended to show the sequence of messages which
  257. occurs during a drop operation, and to enable testing/debugging of drag/drop
  258. applications.
  259.  
  260. The DROPINFO example comes with a command file named BUILD.CMD, which invokes
  261. the NMAKE utility.
  262.  
  263.  
  264. **************************************************************************************
  265.  
  266. DMCUST.C - a demo program by Alan Chambers - UK PS Technical Support, whilst on
  267.            a residency at the ITSC, Boca Raton
  268.  
  269. Updated to work with GA code, 6 May 1992
  270.  
  271. This program reads several names, addresses and phone numbers from a file (DMCUST.DAT)
  272. and displays them as icons in a container window.  These items can be moved from
  273. one instance of this program to another by direct manipulation; they can be dropped
  274. on an order form displayed by the DMORDER sample to fill in the customer details therein,
  275. and they can be dropped on the telephone icon shown by the DMPHONE sample, to simulate
  276. a telephone dialer.
  277.  
  278.  
  279. This sample illustrates several different aspects of drag/drop:
  280.  
  281.     - initiating a drag from a container window
  282.     - using the DRM_PRINT rendering mechanism to allow application printing by
  283.       drag/drop to a Workplace Shell printer object
  284.     - using the DRM_DISCARD rendering mechanism to allow deletion of application
  285.       items by dragging them to the Workplace Shell shredder object
  286.     - implementing both ends of a user defined rendering mechanism (here called
  287.       DRM_SHAREMEM)
  288.  
  289.  
  290. The program concentrates on demonstrating drag/drop techniques and is therefore
  291. very simple in other respects. In particular, the so called customers to be displayed
  292. are read from a simple flat file called DMCUST.DAT that can be read with fscanf().
  293. the following lines illustrate the format of this file - note that each text
  294. field must have no imbedded blanks:
  295.  
  296. It does also support
  297. printing by drag/drop to a WPS printer object, and deletion by drag/drop to
  298. the shredder.  This illustrates the use of the DRM_PRINT and DRM_DISCARD
  299. rendering mechanism.
  300.  
  301. Please note that I am demonstrating the use of the DRM_PRINT drag/drop
  302. technique, NOT PM printing.  To keep the sample simple, the actual printing is
  303. done by opening LPT1 and writing data to it - the result is that whichever
  304. printer to drag to, the printing comes out on LPT1.  To put the proper PM
  305. printing in would have distracted attention from the real point of the sample -
  306. ie direct manipulation.
  307.  
  308. **************************************************************************************
  309.  
  310. DMORDER.C - a demo program written by Franco Federico and Alan Chambers
  311.             whilst on a residency at the ITSC, Boca Raton
  312.  
  313. Updated to work with GA code, 6 May 1992
  314.  
  315. This program will display an order form when the appropriate action bar selection
  316. is made.  Customers, dragged from the DMCUST sample program, can be dropped onto
  317. this order form, with the result that the customer's details are entered into
  318. the appropriate fields.
  319.  
  320. The code for the window and dialog box, and the technique used for subclassing
  321. were written by Franco, the drag/drop code added by Alan.
  322.  
  323.  
  324. **************************************************************************************
  325.  
  326. DMPHONE.C - a demo program by Alan Chambers - UK PS Technical Support, on residency
  327.            at the ITSC, Boca Raton
  328.  
  329. Modified 6 May 1992 to work with GA code.
  330.  
  331.  
  332. This program is designed to be used with the DMCUST sample program.  A customer
  333. can be dragged onto the telephone icon displayed by this program, with the result
  334. that a series of beeps, reminiscent of touchtone dialling tones, are sounded.
  335.  
  336. The program illustrates the use of a private rendering mechanism, DRM_SHAREMEM, from
  337. the target's point of view.
  338.  
  339. The program displays a telephone icon as using the WC_STATIC class, then subclasses
  340. this static window to add function for drag/drop, moving the icon around the desktop,
  341. and providing a context (pop-up) menu.
  342.  
  343. *************************************************************************************
  344.  
  345.  
  346.  
  347. The other Redbooks, covering OS/2 Version 2.0 are:
  348.  
  349.  
  350. GG24-3730  "OS/2 Version 2.0 - Volume 1: Control Program"
  351.  
  352. (Sample code available in package RB3730.ZIP on CompuServe
  353.  and GG243730 PACKAGE on OS2TOOLS)
  354.  
  355. GG24-3731  "OS/2 Version 2.0 - Volume 2: DOS and Windows Environment"
  356.  
  357. (Sample code available in package RB3731.ZIP on CompuServe
  358.  and GG243731 PACKAGE on OS2TOOLS)
  359.  
  360. GG24-3732  "OS/2 Version 2.0 - Volume 3: Presentation Manager & Workplace Shell"
  361.  
  362. GG24-3775  "OS/2 Version 2.0 - Volume 5: Print Subsystem"
  363.  
  364. ------------------------------------------------------------------------
  365.  
  366.